Embedded content can be added dynamically to a page using any programming language that can generate HTML - providing a more sophisticated set of capabilities than the simple cut-and-paste capability from the Pyramid application. Using Pyramid's content REST APIs, it would also be possible to automatically extract the content IDs needed instead of hard-coding them in the host page - providing the basis for a custom content viewer that can be tailored for each individual user.
Note: As of version 2020.10, the Embed APIs approach is recommended, since it provides a more object oriented approach to embedding with formal support for React, Angular, and TypeScript - all operating via NPM. For details of the Embed API v2.0, see Embed API.
Embed API
The embedding process is meant to be simple and effective without complexity. However, there are a few functions required when not using the simple cut-and-paste model:
- pyramid.embed(element, options) - explained below
- pyramid.runAll() - Runs all visuals currently hosted on the page
- pyramid.runById(id) - Runs a specific visual, using its ID
- pyramid.stop(element) - explained below
- pyramid.stopAll() - Stops loading all visuals and disposes them from the host page heap
- pyramid.stopById(id) - Stops a specific visual, using its ID
Embed function
This function takes 2 parameters: the first one is an HTML element or a selector.
//html element var container = document.getElementById('container') pyramid.embed(container, options) // or, you can pass the selector of the html element pyramid.embed('#container', options)
The second parameter is the configuration object for the embedded content
type Options = { id: string, //required host: string, // required contentType: string, // required params: ExternalParameters // optional }
Example:
var options = { id: "f8d66c64-893b-43fc-8049-e9b710ec90f9", host: "https://mysite", contentType: "discovery" }
The last params parameter is for adding filters to the content. Click here for more details on the parameterization syntax.
pyramid.stop
This function will stop the running embedded content
// html element var container = document.getElementById('container') pyramid.stop(container) // or, you can pass the selector of the html element pyramid.stop('#container')
Dynamic Embed Example
The following example demonstrates how to programmatically load embedded content to a page using JavaScript and jQuery.
Note: This does not cover the authentication steps, which need to be addressed separately.
<!-- add a container element to the page --> <div class="container"></div> <!-- add the embed and jquery scripts --> <script src="https://code.jquery.com/jquery-2.2.4.min.js"></script> <script src="https://mysite/no-shell/embed.js"></script> <script> function runEmbed() { // get the container element var container = $('.container') // set width and height on the element container.width(1000).height(400) // embed the report content in the container pyramid.embed(container.get(0), { id: "f8d66c64-893b-43fc-8049-e9b710ec90f9", host: "https://mysite", contentType: "discovery" }) } window.onload = function() { runEmbed() } </script>
Setting filters for embedded content
To use filter parameters in an embedded discovery, send a params object to the pyramid.embed function as the last parameter
pyramid.embed(container.get(0), { id: "f8d66c64-893b-43fc-8049-e9b710ec90f9", host: "https://mysite", contentType: "discovery", params: { reportFilters: [{ value: "[Customer].[Country].[United States]" }, { value: "[Date].[year].[2010]" }] } })